How to create and edit a data entry Form

When a Programme Lead accesses a project, any Forms, Editors and Statistics tools already created will be listed, along with options to edit, delete and add new instances of them, e.g.:

To build a new Form, click in the Forms section. The Form creator displays:

Form creator

Here you configure a Form, add elements to it, and assign permissions to users (specify who can use this specific Form; who can modify it).

To edit an existing Form, click Edit beside a Form's title. The Form will open ready for editing.

All of the configurable and editable elements of a Form are described below:

Title

A descriptive name for the Form, which will display for users.

Description

A description of the Form or details about how to use it.

When provided, users will see an Information icon alongside the title:

Information icon

Clicking the icon will display a pop-up with the description:

Form description

Identifier

A descriptive identifier for the Form. When creating a Form you can provide an alphanumeric identifier, or you can leave the field blank and an alphanumeric identifier will be assigned automatically.

For the most part it is irrelevant whether the identifier is an alphanumeric value provided by the system or a descriptive label provided by a Programme Lead as it is only referenced behind the scenes by various components of Sapphire, or used to construct the URL for the Form.

There are situations when it might be handy to assign a descriptive identifier however, e.g.:

  • To substitute an otherwise meaningless alphanumeric value in the URL with a user-friendly descriptor.
  • If using a processing script as the script is named using the identifier. See Perform some special processing for more details.

Note: If providing an identifier, it is recommended that it is constructed from letters, numbers, hyphens and underscores only (no spaces).

Table

Specify which EMu module will be updated when the Form is saved (a record will be created or updated in this module).

A filtered drop list of module names will display as you enter characters in the Table field. Select a module name from the list:

Table field

Note: When presented with a drop list of values, it is best practice to select an entry from the list rather than keying the value into the field.

Deferrable

The Deferrable option is intended for wireless devices and affects the order in which records are processed if wireless connectivity is lost.

Options include:

No

This is the default setting and in most cases can be left as such.

Yes

When Yes is selected and wireless connectivity is lost, a queue is created for any new records. Records are added to the end of the queue to ensure that when a connection is re-established the records are saved in the order in which they were created.

The Deferrable option is intended for wireless devices and affects the order in which records are processed in the event that wireless connectivity is lost. By default (Deferrable = No): if wireless connectivity is lost, record save will fail and an error message will be generated.

When Deferrable is set to Yes and a device is unable to save a record due to loss of wireless connectivity:

  • A queue of unsaved records is created.
  • Each unsaved record is added to the end of the queue. This ensures that when a connection is re-established and the records are saved, they are saved in the order in which they were created (oldest first).
  • The system will attempt to save the queued records at regular intervals until all records are removed from the queue:
    • If a save attempt is successful, the record is removed from the front of the queue and an attempt is made to save the next record, and so on until the queue is empty.
    • If a save attempt fails for reasons other than connectivity, an error message is recorded and the save data is removed from the front of the queue, and an attempt is made to save the next record, and so on until the queue is empty.
  • Three icons are added to Sapphire:

    		•

    WiFi connection status. Icon is filled when there is a connection. When connection is lost, the icon displays as:

    Error notification. When saving records fails for any reason other than connectivity, the icon display as:

    Click the icon to view error messages.

    When there are records waiting to be saved, the top bulb of timer icon is filled:

    At regular intervals the system will attempt to save any queued records. When records are successfully saved, the timer reverts to its original form (empty top bulb).

Processing script

Here we specify the name of a script that can manipulate Form data in any number of ways. A typical use of a Processing script is bulk creation of records. Ignore this field if you are not using a Processing script.

Details here.

In this example (creating a new Form), no Identifier has been entered. When the Form is saved, an identifier will be assigned automatically:

Create form

Three permissions for project elements (Forms, Editors, Statistics) can be assigned :

none

This is the default state for Everyone when a project element is created: the element is not available to users and will not be listed when they log in.

use

When assigned, the project element will be listed when an authorized user logs in. The user can use the project element but not modify it.

edit

When assigned, the project element will be listed when an authorized user logs in. The user can use the project element, modify and delete it.

When the project element is listed in the Dashboard, the edit Edit and delete icons will display beside its name.

To change access permissions that affect all users of a project element, select the appropriate permission from the Everyone drop list:

Permissions

To change access permissions to a project element for a specific user or group:

  1. Click .

    Additional fields display:

    Add permissions

  2. Select user or group from the first drop list.
  3. Begin keying a user or group name in the second field and select a name from the list of suggestions that will display:

    Key group name

  4. Select a permission from the Permissions drop-list:

    5. Permissions

Note: Click beside an assigned user or group permission to remove it.

To add a section to the Form:

  1. Click .

    2. A Form can have multiple sections (or just one) with logical groupings of fields.

  2. Provide a descriptive name for the section in the Label field:

    Section

    A read-only ID is assigned automatically.

    Section IDs are used when designing a Custom Layout. Details here.

    This will remove the section, along with any fields in the section.

    and

    Collapse and expand sections.

To add a field to a section, click :

Add field

For each field we specify:

Used by the system to identify the field.

To keep things simple, it is recommended that the Identifier is the same as Label but lower case and without spaces. For instance, if Label is First Name, Identifier could be firstname.

An identifier is required, and it must be unique in this Form.

The back-end name of the field that will be updated when the Form is saved. As the back-end field name is keyed into the Column field, a drop list of available column names will display. Select a column name from the drop list.

Note: Unless a processing script allows for it, a column should only appear once on a Form.

Fields are restricted to those available in the module specified in the Table field above.

Depending on the type of field specified in Column, various values will be auto-completed. For instance, if you specify an attachment field in Column, Type will automatically be set to attachment and Ref. Table, Ref. Column and Match Limit will be completed.

A descriptive label for the field that will display to its left on the Form, e.g. First Name.

Note: When adding an image control to a Form, it may be better to exclude a Field label in order to maximize the size of the image control. This is particularly important when using a custom layout with columns.

Options are:

image

Use to display an image in the Form.

capture

Enable users to locate multimedia of any kind that is accessible to their device and upload it.

Note: capture does not allow users to take a photo with their device and upload it.

image-capture

Enable users to locate an image accessible to their computer / device and upload it.

Note: image-capture may enable users to take a photo with their device and upload it, depending on their mobile device.

mobile-image-capture

Enable a user with a mobile device to capture an image with the device's camera and upload it.

 

Note: For details of these first four image options, see Multimedia fields.

single

The default value for Kind.

multiple

A table of values, e.g. Other Names: (Person Details) in the Parties module. When a table of values is specified in Column, Kind is automatically set to multiple.

See Kind: multiple for details.

Options are:

attachment

Allow a user to create an attachment.

See Attachment field for details.

date

The date picker pop-up will display when the cursor is placed in the field.

See Type: date for details.

integer

For integers only.

number

For floating point numbers.

selection

Where Column has an associated Lookup List, specifying a Type of selection will present users with a drop list of read-only values drawn from Column. In this case it is not necessary to specify the name of the Lookup List on Lookup.

If a Lookup List is specified in Lookup, users will be presented with values drawn from the specified Lookup List (it can be any Lookup List).

See Type: selection for details.

text

Where Column has an associated Lookup List, specifying a Type of text will present users with a filtered drop list of read-only values drawn from Column. Filtering occurs as the user enters characters in the field.

If a Lookup List is specified in Lookup, users will be presented with values drawn from the specified Lookup List (it can be any Lookup List).

See Type: text for details.

Used where:

  • Kind = single

    -AND-

  • Type = text

Specify the height (number of lines) of the text field.

Determines whether the field can be edited or not. Options are:

editable The default access.

hidden

The field is not shown on the screen.

hidden is useful when used in conjunction with a default value (see Default below): it is possible to specify a default value for the field and hide the field from the Form's user, preventing the value from being modified and ensuring it is always added to the record created.

read-only

The field is visible but not editable.

Options are:

optional The default option; users may enter data in the field or leave it blank.

mandatory

The field must be completed in order for the Form to be saved.

suggested

The field should be completed but it will be possible to save the record if not.

An icon is added to fields that are specified as mandatory () and suggested (). If a Form is saved with one or more incomplete mandatory fields, the save will be prevented until the fields are completed.

If a Form is saved with one or more incomplete suggested fields, the user will be alerted but will be able to save the record anyway.

When a field is specified as having a Type of selection or Text and Column has an associated Lookup List, a user is presented with a list of read-only values drawn from the Column specified.

The Lookup option is used:

  • In conjunction with selection or text and Column. Specify the back-end name of a Lookup List to present its values to a user instead of the values drawn from Column.

    This can be useful, for instance, if Column includes a large number of entries and only a small number are required for the purposes of data entry.

  • Where no Column has been specified when using a Processing Script to perform some special processing.

    Specify the back-end name of a Lookup List to present its values to a user. If the Lookup List is a multi-level hierarchy, use the Level field (see below) to specify which level of the hierarchy to display.

See Lookup for details.

If the Lookup List specified in Lookup is a multi-level hierarchy, use the Level field to specify which level of the hierarchy to display.

See Lookup for details.

A value to be added to the field by default when a new record is commenced in the Form.

Useful in conjunction with the hidden option (see Access above). It is possible to specify a default value for the field and hide the field from the data entry user, preventing the value from being modified and ensuring that it is always added to the record created.

When an attachment field is specified in Column, a user is presented with a text box; when a value is entered in the text box, a search is performed in Ref. Column in the targetClosed An attachment is made from one record to another. The record from which the attachment is initiated is the Primary record; the record that is attached is called the Target. module (Ref. Table) and matching results are listed (up to the number specified in Match Limit) from which the user can select a record. On saving the Form, an attachment is made from Column to the record selected in the target module (the IRN of the attachment record is saved in Column).

When an attachment column is specified in Column:

  • The table to which it attaches is automatically specified in Ref. Table, and Ref. Column is set to SummaryData; a default number (20) is added to Match Limit.
  • It is possible to specify a Filter to restrict which records are returned by the search of the target module.

Details:

Ref. Table

 The back-end name of the table to which the attachment field specified in Column attaches. Auto-completed when an attachment field is specified in Column.

Ref. Column

By default, Ref. Column is set to SummaryData. This is the column searched when a user enters a value in the Search field of the Form.

The column searched can be changed to any column in Ref. Table.

Match Limit

The maximum number of results to display to the user. A default number (20) is specified, but this can be changed as required.

Add filter term

Where Type is attachment it is possible to specify a Filter that restricts which records are returned by a search of Ref. Table.

Click Add filter term to specify a Column and Value to restrict which records can be attached to.

See Attachment field for details.

Add field

Add as many fields to the section as required by clicking .

If it makes sense to organize fields into logical groupings rather than adding them all to a single section, click to add another section to the Form.

In this example we could add a section called Address to group address details separately from the Party's name:

Add section

Note: Note that an ID has been assigned automatically for this second section. We look at how to reference Section IDs in designing a Custom Layout for a Form.

In this screenshot the first section has been collapsed to conserve screen space: the number of fields in the collapsed section is indicated beside the section label (Name in this example).

It is possible to drag and drop a field within a section (to change its position on the Form) and between sections. It is also possible to drag and drop sections in order to rearrange their order on the Form. While not necessary, it can be handy to collapse sections before dragging them.

Click Save to save the Form.

If you did not specify an Identifier for the Form, it will be assigned automatically.

The Form undergoes validation. It will not be possible to save the Form until all mandatory fields have been completed.

When finished with the Form, click:

Return to the Home screen.

If you belong to more than one project, the Home screen lists all the projects you belong to. If you belong to one project only, the Home screen lists the elements of the project that you have access to.

-OR-

 

Return to the list of elements you have access to in the current project.

Note: If you belong to one project only, the Home and Project buttons return you to the same location.

-OR-

 

Exit the application.
More details